<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta http-equiv="Content-Language" content="en" />
    <title>s6: the s6-fdholder-setdump program</title>
    <meta name="Description" content="s6: the s6-fdholder-setdump program" />
    <meta name="Keywords" content="s6 s6-fdholder fd-holding fd-holder fd dump storage unix socket activation" />
    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
  </head>
<body>

<p>
<a href="index.html">s6</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>

<h1> The <tt>s6-fdholder-setdump</tt> program </h1>

<p>
<tt>s6-fdholder-setdump</tt> connects to a
<a href="s6-fdholderd.html">fd-holding daemon</a> listening on a
Unix domain socket, and dumps a set of file descriptors into
that daemon.
</p>

<h2> Interface </h2>

<pre>
     s6-fdholder-setdump [ -t <em>timeout</em> ] <em>path</em>
</pre>

<ul>
 <li> <tt>s6-fdholder-setdump</tt> connects to a
<a href="s6-fdholderd.html">s6-fdholderd</a> server process listening on
<em>path</em>. </li>
 <li> It attempts to pass a complete state - i.e. a set of file descriptors
with identifiers and expiration dates - to the server. </li>
</ul>

<h2> Options </h2>

<ul>
<li> <tt>-t&nbsp;<em>timeout</em></tt>&nbsp;: if the operation cannot be
processed in <em>timeout</em> milliseconds, then fail with an error message.
Communications with the server should be near-instant, so this option is
only here to protect users against programming errors (connecting to the
wrong socket, for instance). </li>
</ul>

<h2> Exit codes </h2>

<ul>
 <li> 0: success. </li>
 <li> 1: the server denied the operation. The meaning of the error messages
is explained <a href="s6-fdholder-errorcodes.html">here</a>. </li>
 <li> 100: wrong usage. </li>
 <li> 111: system call failed - this includes attempting to connect to a
nonexistent socket, or one where no <a href="s6-fdholderd.html">s6-fdholderd</a>
daemon is listening. </li>
</ul>

<h2> Notes </h2>

<ul>
 <li> The file descriptors to transmit to the server should of course be
already open in the <tt>s6-fdholder-setdump</tt> program; also, <tt>s6-fdholder-setdump</tt>
should have certain environment variables that describe that set of file
descriptors. The format of the environment is the same as the one set by
<a href="s6-fdholder-getdump.html">s6-fdholder-getdump</a>. </li>
 <li> Setting the whole state of an s6-fdholderd daemon requires specific
privileges. Make sure you properly
<a href="s6-fdholderd.html#configuration">configure the s6-fdholderd
access rights</a> so your client can perform that operation. </li>
 <li> Previously held fds will still be kept by the server (so, "setting"
the state is more like "adding to" the state), unless there is an identifier
collision, in which case the fd in the transmitted set takes precedence and
the previously held fd is overwritten. </li>
</ul>

</body>
</html>
